51.2.5 Per-Directory Local Variables

Sometimes, you may wish to define the same set of local variables to all the files in a certain directory and its subdirectories, such as the directory tree of a large software project. This can be accomplished with directory-local variables.

The usual way to define directory-local variables is to put a file named .dir-locals.el²⁰ in a directory. Whenever Emacs visits any file in that directory or any of its subdirectories, it will apply the directory-local variables specified in .dir-locals.el, as though they had been defined as file-local variables for that file (see File Variables). Emacs searches for .dir-locals.el starting in the directory of the visited file, and moving up the directory tree. To avoid slowdown, this search is skipped for remote files. If needed, the search can be extended for remote files by setting the variable enable-remote-dir-locals to t.

The .dir-locals.el file should hold a specially-constructed list, which maps major mode names (symbols) to alists (see Association Lists in The Emacs Lisp Reference Manual). Each alist entry consists of a variable name and the directory-local value to assign to that variable, when the specified major mode is enabled. Instead of a mode name, you can specify ‘nil’, which means that the alist applies to any mode; or you can specify a subdirectory name (a string), in which case the alist applies to all files in that subdirectory.

Here’s an example of a .dir-locals.el file:

((nil . ((indent-tabs-mode . t)
         (fill-column . 80)))
 (c-mode . ((c-file-style . "BSD")
            (subdirs . nil)))
 ("src/imported"
  . ((nil . ((change-log-default-name
              . "ChangeLog.local"))))))

This sets ‘indent-tabs-mode’ and fill-column for any file in the directory tree, and the indentation style for any C source file. The special subdirs element is not a variable, but a special keyword which indicates that the C mode settings are only to be applied in the current directory, not in any subdirectories. Finally, it specifies a different ChangeLog file name for any file in the src/imported subdirectory.

Instead of editing the .dir-locals.el file by hand, you can use the command M-x add-dir-local-variable. This prompts for a mode or subdirectory name, and for variable and value, and adds the entry defining the directory-local variable. M-x delete-dir-local-variable deletes an entry. M-x copy-file-locals-to-dir-locals copies the file-local variables in the current file into .dir-locals.el.

Another method of specifying directory-local variables is to define a group of variables/value pairs in a directory class, using the dir-locals-set-class-variables function; then, tell Emacs which directories correspond to the class by using the dir-locals-set-directory-class function. These function calls normally go in your initialization file (see Init File). This method is useful when you can’t put .dir-locals.el in a directory for some reason. For example, you could apply settings to an unwritable directory this way:

(dir-locals-set-class-variables 'unwritable-directory
   '((nil . ((some-useful-setting . value)))))

(dir-locals-set-directory-class
   "/usr/include/" 'unwritable-directory)

If a variable has both a directory-local and file-local value specified, the file-local value takes effect. Unsafe directory-local variables are handled in the same way as unsafe file-local variables (see Safe File Variables).

Directory-local variables also take effect in certain buffers that do not visit a file directly but perform work within a directory, such as Dired buffers (see Dired).